feat(types): declare RichtextFieldMetadata for the widget's third registry key - #8373

Fixes #7083

Executes the maintainer's ruling of 2026-09-07 (director seat, decision batch #71, comment 5565745438): the three registry keys one widget serves each get an exported metadata type. RichtextFieldMetadata is added to @object-ui/types, joins the FieldMetadata union, and the deliberate as unknown as MarkdownFieldMetadata in packages/fields/src/widgets/__tests__/RichTextField.rows.test.tsx — with the comment above it — is gone.

Contract-review rework — round 2

A CONTRACT_REVIEW_TIER review returned FAIL with three reproducible items. The member's shape was judged correct and evidenced, and is untouched by this round: no change to the member, the union, the barrel, or any test's logic. What changed is one docs page and three pieces of prose that were false.

R1 — this diff had made a published docs page false

content/docs/fields/rich-text.mdx said markdown and html "are two field types served by one widget", that "each has its own exported metadata type", and that "there is no combined 'rich text' metadata type". The page never mentioned the richtext key at all. Declaring RichtextFieldMetadata is exactly what made those sentences false, and leaving them would have restarted the rediscovery loop the ruling exists to end.

Corrected by following the objectui#7061 precedent, which updated this same page for the analogous rows change:

The Editor Modes entry is the same correction applied to the same page: the section enumerates the widget's modes and stopped at two. The seat's authorisation for this file-surface widening covers content/docs/fields/rich-text.mdx and nothing else; no other doc page is touched, and content/docs/releases/ is untouched.

R2 — the published TSDoc stated a false claim, for the wrong reason, citing the wrong pin

Three sub-items, all in RichtextFieldMetadata's max_length section of packages/types/src/field-types.ts and mirrored in the changeset body.

1. The "symmetric on every measurable axis" claim is dropped — it is false. Located by content, not by line: ObjectForm forwards max_length to the HTML maxlength attribute under if (field.type === 'text' || field.type === 'textarea' || field.type === 'markdown' || field.type === 'html'), and EmbeddableForm's DEFAULT_MAX_LENGTH record lists text, email, url, phone, textarea, markdown, html. richtext is absent from both.

before — "It is declared because the cross-check against MarkdownFieldMetadata and HtmlFieldMetadata found richtext symmetric with both on every axis that can be measured, not because they happen to have it"

after — "RichTextField never reads this key. It is declared because a live reader outside the widget does, on every field regardless of type"

2. The real reader is now stated, and it is checkable. The spec-symmetry argument is non-discriminating for this key: FieldSchema answers identically for every field type, text included, on maxLength and max_length, so it says nothing about richtext versus its siblings. The reader the round-1 derivation missed is buildValidationRules in packages/fields/src/index.tsx:

const maxLength = (field as any).maxLength ?? field.max_length;
if (maxLength) {
  rules.maxLength = { value: maxLength, message: …, messageKey: 'validation.maxLength' };
}

Generic — no field-type gate anywhere in the function. It is applied to every field by ObjectForm (validation: buildValidationRules(field)) and by the identical line in sectionFields.ts; the form renderer spreads the result into the react-hook-form rules object and localizes the maxLength entry. ⇒ max_length on a richtext field is enforced at submit. That is the checkable reason the key is declared, and it now replaces the symmetry argument in both the docblock and the changeset. The two sites that do not reach richtext are stated alongside it, so the boundary cannot be re-derived as symmetry.

3. The pin citation is re-pointed. The docblock credited richtext-field-metadata-7083.test.tsx for three facts; that file pins only two of them.

Carried into the pin test's own docblock. That file repeated the same false rationale — "Putting it on the new member was a decision, and it rests on this reading rather than on the two siblings having it" — while being cited by the corrected docblock, so it is corrected with it. Comment-only, proven: stripped of every block and line comment, the file hashes c1d01d39c24f2ada70c58b52b8fa829574594315875f5d3ffc17bcccc65b74bf both before and after, at 68 non-comment lines either way. No assertion, fixture or describe body is touched.

R3 — the PR body contradicted its own diff

Since de98ffd3 this body was false in three places. The reviewer independently verified that the RichTextField.tsx edit is comment-only (stripped-of-// hashes identical, 0 non-comment lines changed, and the comment text appears nowhere in built dist/), so the correction is wording, not code.

All three are corrected in place below. The read-site table has also lost its line numbers, which had drifted with the merge; it now anchors on the expressions themselves.

What was missing

markdown, html and richtext are one widget (#5498). Two of the three carried an exported metadata type; richtext carried none, so the runtime served it happily by structure while an author could not write its metadata under an annotation at all. The state was neither a member nor a recorded alias — a silent gap whose only evidence was a cast in this repo's own pin test. That asymmetry is why the gap had to be rediscovered to be seen, and #7083 is itself that rediscovery.

So the comment goes with the cast, and the surrounding docblock in that file is re-pointed: the next reader should not be able to find the gap again.

The read set was DERIVED, not copied

The ruling's load-bearing sentence is "do not copy 'probably the same'". Every key was read off packages/fields/src/widgets/RichTextField.tsx on the richtext path. That file carries a comment-only edit in this change — the stale comment described in 验收备注 1 — and ships nothing: its executable text is byte-identical, and the reviewer confirmed the comment text appears nowhere in the built dist/.

The readonly branch hands field whole to the RICH_TEXT_CELL_RENDERERS entry for the type; both renderers in richTextDisplay.tsx destructure value only, so the display half contributes no metadata key. type is also the only thing that differs between the three keys at runtime — it selects the display pipeline (richtext reads through the HTML renderer, #5452) and the format label. Nothing else in the widget branches on it.

The one key that needed a decision

MarkdownFieldMetadata and HtmlFieldMetadata are byte-identical to each other apart from their type literal: type + max_length?: number + rows?: number over BaseFieldMetadata. So the cross-check produced exactly one open question — max_length, the one key on the siblings that RichTextField does not read.

It is declared, because a live reader outside the widget reads it on every field: buildValidationRules (see R2 above) compiles it into a submit-time react-hook-form rule with no field-type gate, and both form producers call it on every field they build. A max_length written on a richtext field is therefore enforced when the form is submitted.

⚠️ It is not forwarded to the editor's HTML maxlength attribute, and it gets no default cap in EmbeddableForm — both of those enumerate field types and omit richtext. Those two omissions predate this PR, are not this PR's, and are not touched here.

Separately — and not the reason for the key — the authoring boundary at @objectstack/spec 17.3.0 answers identically for all three of the field types this widget serves. That reading is non-discriminating (every field type answers the same way, text included) but is pinned anyway so the docblock cannot rot into a false canonical claim about the spelling:

rows: 4 is admitted for all three too, and that half is pinned in packages/types/src/__tests__/select-option-spec-extension-7014.test.ts, not in this PR's file.

The pin has two halves, and both are non-vacuous

packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx:

• compiles — the literal is annotated, never as, so TypeScript's excess-property check judges every key, and it is assigned to FieldMetadata to pin the union membership the ruling granted plus the narrowing on type. Measured, not assumed, that this leg actually runs: packages/fields's type-check script is tsc --noEmit && tsc -p tsconfig.test.json, and tsc -p tsconfig.test.json --listFiles names both this file and RichTextField.rows.test.tsx. On the pre-change tree the file does not compile at all — there is no member to annotate against — which is what makes this leg real rather than decorative. A pin proving only the render would still have passed with the cast in place, i.e. in the state this card ends.
• renders — rows, placeholder, mobile_fullscreen and label are each asserted at the DOM, against a control fixture with all the optional keys absent at once, so a green reads "the widget consumed the declared key" and never "the default happened to match".

Scope

Additive only. Nothing is removed or narrowed; richtext metadata previously written through a cast keeps compiling; RichTextField's behaviour is untouched — it already served all three keys, and this change only gives the third one a face. Round-1 downstream sweep: turbo run type-check --filter='...@object-ui/types' — 77/77 tasks green, so widening the FieldMetadata union breaks no consumer.

packages/fields changes are test-only plus one comment-only edit (RichTextField.tsx), proven to ship nothing, so the changeset grades @object-ui/types minor and nothing else.

Verification — round 2

Merged origin/main in first (9b1b105d, merge, never rebase; conflict-free) because the PR's mergeable_state read unknown on two consecutive API reads rather than clean. Every reading below is from after that merge, on the pushed head. Exit codes captured before any pipe (cmd > log 2>&1; EXIT=$?), each verdict read from the gate's own printed line.

Beyond the gates, a control-byte self-scan over the four touched paths (grep -naP over the C0 range plus DEL) found none.

check:doc-snippets compiles fences against built dist/*.d.ts, so its closure (--build-filter, 34 packages) was rebuilt after the merge before the reading above was taken — an unbuilt tree exits 2 there and is not a verdict about any document.

The new fence is proven compiled, not assumed

The gate reports a block count, not which block is yours, so a red/green pair was measured rather than inferred. Mutation and restore both anchored on the target text and verified on disk:

• mutation — toolbar: ['bold'] injected into the articleBody: RichtextFieldMetadata literal. On-disk proof: injected text present exactly 1 time; blob 8bfe7787… → 49956cd3… (a no-op mutation would have failed the run loudly).
• red leg — check-doc-snippet-types.mjs exit 1, naming the file: [semantic] content/docs/fields/rich-text.mdx:52:3 TS2353: Object literal may only specify known properties, and 'toolbar' does not exist in type 'RichtextFieldMetadata'. · Semantic phase: 632 of 632 block(s) judged, 1 failed.
• restore leg — git checkout HEAD -- content/docs/fields/rich-text.mdx (never a bare git checkout --; the implementation was committed first, so HEAD carries it). Proven by state, not by exit code: working blob back to 8bfe7787…, identical to the HEAD blob, and git diff HEAD empty. The script carried a trap … EXIT INT TERM restore with an absolute repo-root path throughout.
• green leg — gate re-run after restore: exit 0, Semantic phase: 632 of 632 block(s) judged, 0 failed.

⇒ the gate does read the new RichtextFieldMetadata literal, and it can fail on it.

验收备注

Observations. None is filed as a card by this seat.

1. RichTextField.tsx's metadata-face comment was stale after the member landed, and it was corrected — in de98ffd3, not left. Its old text said the third key "has no union member of its own"; it now names RichtextFieldMetadata and explains why the cast below it still names only two of the three. The edit is comment-only: stripped-of-comment hashes identical, 0 non-comment lines changed, and the comment text appears nowhere in built dist/. The round-1 body claimed the file was untouched; that claim is what R3 corrected.
2. The rows docblocks on MarkdownFieldMetadata and HtmlFieldMetadata still describe the @objectstack/spec 17.2.0 boundary (where rows was refused by name); at 17.3.0 it is admitted. That prose is When the @objectstack/spec pin moves to 17.3: PR #7510 / #7520's comment "repairs" become FALSE — rows and options[].description are now declared keys #7635's declared surface, so this PR states the 17.3.0 reading for richtext only and does not correct the neighbours.
3. Noted, not filed — richtext is missing from three pre-existing enumerations. ObjectForm's maxlength-attribute forwarding, EmbeddableForm's DEFAULT_MAX_LENGTH, and designer.ts's DESIGNER_FIELD_TYPES each list field types and omit richtext, even though one widget serves all three. They are real, they predate this PR, and touching any of them would widen it. The dispatching PM seat is filing the finding card; this seat files nothing and changes nothing there.

Review

Clause-② applies (a new published type-face member), so needs:contract-review is hung on this PR as well as on the card, and stays — this round does not clear it. This PR stays draft, is not enqueued, and has no auto-merge armed; parking green is the intended end state until a fresh CONTRACT_REVIEW_TIER review passes. No label was added or removed and no review was submitted by this seat.

Authored by the domain:spec @ objectui execution seat, session https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX — kept in prose as a code span because a PATCH to this body downgrades a link-form attribution footer and drops the session reference.